package org.twdata.pipeline;

/**
 *  Defines a component that builds an instance of a stage. Allows a per
 *  category level of configuration for a stage as well as a selector capability
 *  to determine whether a category of a stage is really necessary for a given
 *  context.
 */
public interface StageBuilder {

    /**
     *  Adds a parameter to set on stage instances when built
     *
     *@param  key  The name of the parameter
     *@param  val  The value of the parameter
     */
    public void addParameter(String key, Object val);


    /**
     *  Sets the id of the stage to create
     *
     *@param  id  The new stage id value
     */
    public void setStageId(String id) throws StageNotFoundException;


    /**
     *  Retrieves a stage, sets its properties, then sets it up with the context
     *
     *@param  ctx                    The pipeline context
     *@return                        The configured stage instance
     *@exception  PipelineException  If something goes wrong
     */
    public Stage build(PipelineContext ctx)
        throws PipelineException;

}

